Cloudinary の Node.js SDK を試してみた

Cloudinary SDK の Node.js を使って操作する方法をご紹介します。

#Node.js

#デザイン

#Cloudinary

Ito ma

2019.10.30

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

画像最適化SaaSのCloudinaryの SDK ライブラリは様々な言語でサポートされています。今回は Node.js の始め方をご紹介します。

ライブラリのインストール

2020年8月20日、Nodeインストールとドキュメントを追記し、Cloudinaryライブラリのインストールを更新しました。

Node.js をインストールします。（最新の手順は nvm ドキュメントを確認してください！）

% curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash
% nvm install node
% node -v
v14.8.0
% npm -v
6.14.7

ドキュメントを参考に、Cloudinary のライブラリをインストールします。（こちらも最新の手順はドキュメントをご確認ください！）

$ npm install cloudinary
+ cloudinary@1.22.0
added 4 packages from 6 contributors and audited 4 packages in 1.222s

$ npm ls
/Users/maiito
└─┬ cloudinary@1.22.0
  ├── core-js@3.6.5
  ├── lodash@4.17.20
  └── q@1.5.1

クレデンシャル設定

クレデンシャルは、Cloudinary メソッドへの各呼び出しで指定するか、環境変数か config メソッドを使ってグローバルで指定します。

環境変数として指定する場合は、下記のような形式となりますが、ダッシュボードの "Environment variable" から丸ごとコピーできます。

export CLOUDINARY_URL=cloudinary://my_key:my_secret@my_cloud_name

config メソッドを使用する場合は、上記の情報を使用して下記例のように示します。

cloudinary.config({ 
  cloud_name: 'sample', 
  api_key: '874837483274837', 
  api_secret: 'a676b67565c6767a6767d6767f676fe1',
  secure_distribution: 'assets.example.com',
  cname: 'assets.example.com',
  private_cdn: true,
  upload_prefix: 'https://api-ap.cloudinary.com'
});

※ cloud_name、api_key、api_secretは必須項目で、それ以降は任意です。詳細はこちらのドキュメント参照。

※ upload_prefix はアカウントのエンドポイント設定（プレミアム機能のみ利用可能）が、デフォルトのアメリカではなく、ヨーロッパかアジアパシフィックへ変更している場合に指定します。この設定されており、このパラメータの指定がないと、Cloud XXX belongs to ap geo, please access via api-ap.cloudinary.com'のようなエラーが返されます。

そして、コードの先頭には下記の通り Cloudinary クラスを宣言します。

var cloudinary = require('cloudinary').v2;

Node.js SDK のアップロードや管理メソッドでは v2 を含める必要があり、Cloudinary のドキュメントの構文例では毎回これが含まれていますが、この宣言で含めることにより以降の呼び出しでは .v2 を省略してOKです。

実行してみた

では早速、下記の通りなんのオプションもなく手元の画像のアップロードを実行してみました。

$ node
> var cloudinary = require('cloudinary').v2;
undefined
> cloudinary.config({ 
...   cloud_name: 'demo', 
...   api_key: '123', 
...   api_secret: '***' 
... });
> 
> cloudinary.uploader.upload("profile/hoya-matsuri.png", 
...     function(error, result) {console.log(result, error)});

結果は、下記のように出力されました。パブリックID（Cloudinary上でのファイル名）を指定しなかったためランダムの文字列が自動採番され、Cloudinaryのルート直下に画像がアップロードされました。他にも画像の縦横サイズやファイルサイズ、Etagなどの画像の情報、そしてCloudinaryのURLが返されています。

{ public_id: 'hbqdpdk7mybcpgj7dxft',
  version: 1571995054,
  signature: '3a809c70f89c15131c703f2dbeb01aa66f4bde41',
  width: 361,
  height: 361,
  format: 'png',
  resource_type: 'image',
  created_at: '2019-10-25T09:17:34Z',
  tags: [],
  bytes: 157455,
  type: 'upload',
  etag: '3d99ea74d3ed6b5718d97d633d95b1f9',
  placeholder: false,
  url:
   'http://res.cloudinary.com/demo/image/upload/v1571995054/hbqdpdk7mybcpgj7dxft.png',
  secure_url:
   'https://res.cloudinary.com/demo/image/upload/v1571995054/hbqdpdk7mybcpgj7dxft.png',
  access_mode: 'public',
  requester_ip: '<IPアドレス>',
  original_filename: 'hoya-matsuri' } undefined

では、他にもいろいろやってみます。

オプション指定して画像をアップロード (1)

今度はupload メソッドのオプションを指定してアップロードします。下記では、ito-test フォルダ配下に元のファイル名でアップロードしています。

cloudinary.uploader.upload("Photos/Abendessen.jpg", 
  {
    use_filename: true,
    unique_filename: false,
    folder: 'ito-test'  },
  function(error, result) {console.log(result, error)});

アップロード済み画像の名前変更・フォルダ移動

先ほどオプションなしでアップロードした画像のパブリックIDを変更し、フォルダ配下へ移動します。これは、rename メソッドを使用します。

cloudinary.uploader.rename('hbqdpdk7mybcpgj7dxft',
  'ito-test/hoya-matsuri',
  function(error, result) {console.log(result.public_id)});

アップロード済み画像にタグ付け

tags メソッドでアップロードした画像にタグを追加します。

cloudinary.uploader.add_tag('Node.js', 
  ['ito-test/hoya-matsuri', 'ito-test/Abendessen'],
  function(error, result) {console.log(result, error)});

特定タグの画像一覧を確認

resources を使って今度は付与したタグの画像一覧を取得します。

cloudinary.api.resources_by_tag('Node.js',
  {
    max_results: 5
  },
  function(error, result) {console.log(result, error); });

結果は、以下のように出力されました。

{ resources:
   [ { public_id: 'ito-test/Abendessen',
       format: 'jpg',
       version: 1572257756,
       resource_type: 'image',
       type: 'upload',
       created_at: '2019-10-28T10:15:56Z',
       bytes: 792931,
       width: 2304,
       height: 1728,
       access_mode: 'public',
       url:
        'http://res.cloudinary.com/demo/image/upload/v1572257756/ito-test/Abendessen.jpg',
       secure_url:
        'https://res.cloudinary.com/demo/image/upload/v1572257756/ito-test/Abendessen.jpg' },
     { public_id: 'ito-test/hoya-matsuri',
       format: 'png',
       version: 1572250358,
       resource_type: 'image',
       type: 'upload',
       created_at: '2019-10-28T08:12:38Z',
       bytes: 157455,
       width: 361,
       height: 361,
       access_mode: 'public',
       url:
        'http://res.cloudinary.com/demo/image/upload/v1572250358/ito-test/hoya-matsuri.png',
       secure_url:
        'https://res.cloudinary.com/demo/image/upload/v1572250358/ito-test/hoya-matsuri.png' } ],
  rate_limit_allowed: 5000,
  rate_limit_reset_at: 2019-10-28T11:00:00.000Z,
  rate_limit_remaining: 4990 }

オプション指定して画像をアップロード (2)

今度は、ローカルの画像ではなくパブリックURLの画像をアップロードしてみます。オプションでパブリックIDを指定し、タグ付与して、結果のうちHTTPS画像URLを取得しています。

cloudinary.uploader.upload("https://mesoko.jp/wp-content/uploads/2018/07/profile-stick-2-1.png",
  { public_id: "ito-test/mesoko", tags: "Node.js" },
  function(error, result) {console.log(result.secure_url, error); });

画像変換用 URL を生成

画像変換パラメータの一覧を参考に、画像変換用のURLを生成することができます。以下は実行したコードと結果です。

> cloudinary.image("ito-test/mesoko",
...   { transformation: [
.....     { width: 300, height: 200, crop: "fill", gravity: "face", quality: 80 },
.....     { overlay: "logo", width: 70, crop: "scale", opacity: 50, gravity: "south_east", x: 10, y: 10 }
.....   ]})
'<img src=\'http://res.cloudinary.com/demo/image/upload/c_fill,g_face,h_200,q_80,w_300/c_scale,g_south_east,l_logo,o_50,w_70,x_10,y_10/v1/ito-test/mesoko\' />'

このURLにアクセスすると、下記のような画像となります。（※上記の結果はドメインを置き換えています）

変換パラメータの詳細についてはこちらの記事もご参考いただけます。

事前に画像を変換

先のように新たに生成した画像URLは、一度URLを開いてアクセスした際に初めて画像変換が行われます。2回目以降のアクセスでは変換した画像のCDNキャッシュが利用されるため高速に配信されますが、1回目のアクセスは少し時間がかかります。

これを避けるために、Explicit メソッドを使ってあらかじめ変換を行うことができます。

cloudinary.uploader.explicit("ito-test/mesoko",
  { type: "upload",
    eager: [
      { width: 200, height: 200, crop: "thumb", gravity: "face" }
    ]},
  function(error, result) {console.log(result, error);} )

コンソールで画像の変換ページから「View derived images」を開くと、上記の変換が既に含まれていることが確認できます。

画像を検索

Search API を使って、ここ3日以内（>3d）でアップロードした画像を検索してみます。

cloudinary.search.expression('uploaded_at>3d').max_results(5).execute().then(result=>console.log(result));

画像を削除

Destroy メソッドを使って単一の画像を削除することができます。ここでは invalidate オプションを付与して、デフォルトでは最大30日保持されるCDNのキャッシュも削除しています。（キャッシュの削除には数分〜最大1時間かかるようです。）

cloudinary.uploader.destroy('ito-test/Abendessen', { invalidate: true },
	function(error,result) { console.log(result, error) });

このメソッドは、こちらの記事にあるように、fetch でキャッシュされた画像や Auto-upload で既に取り込まれている画像を更新する際にも使用できます。

特定タグのすべての画像を削除

再び resources を使って、条件に合う複数の画像を削除することができます。下記はタグ Node.js の付与された画像を削除しています。

cloudinary.api.delete_resources_by_tag('Node.js',
  function(error, result) {console.log(result, error); });

上の destroy と同様、invalidate オプションを入れることで、CDNキャッシュも合わせて削除することができます。

おしまい

以上、Node.js を使って Cloudinary を操作する方法をご紹介しました。今週の Dev.IO でもセッションで Cloudinary についてご紹介します。他にも様々なセッションに加え、相談会ブース、スポンサーブース、そしてコワーキングスペースがありますので、ぜひ遊びに来てください！

Cloudinary について、お問い合わせはこちらから、無料サインアップはこちらから。

PythonからCloudinaryを操作してみた

CloudinaryのPHP SDKを使ってAPIから画像をアップロードしてみた

Cloudinary の Node.js SDK を試してみた

ライブラリのインストール

クレデンシャル設定

実行してみた

オプション指定して画像をアップロード (1)

アップロード済み画像の名前変更・フォルダ移動

アップロード済み画像にタグ付け

特定タグの画像一覧を確認

オプション指定して画像をアップロード (2)

画像変換用 URL を生成

事前に画像を変換

画像を検索

画像を削除

特定タグのすべての画像を削除

おしまい

関連記事

関連記事

主なカテゴリ

AWS

おすすめ

プロダクト

コンテンツ

お問い合わせ

運営会社